[docs] Update documentation for features from 2026-05-14#1338
Open
danielmeppiel wants to merge 1 commit into
Open
[docs] Update documentation for features from 2026-05-14#1338danielmeppiel wants to merge 1 commit into
danielmeppiel wants to merge 1 commit into
Conversation
…g inheritance (#1313, #1290) - install-failures.md: add 'Policy blocked after lockfile wipe' section describing the required-packages-deployed catch-22 and the v0.14 self-healing behavior - policy-debugging.md: add required-packages-deployed as a common block scenario with fix instructions for v0.14+ and older versions - policy-debugging.md: note that dependencies.require/deny now layer correctly through extends: org (fixed in #1290) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
danielmeppiel
added
automation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the troubleshooting documentation to reflect recent policy-related fixes, specifically around required-packages-deployed behavior after deployed_files is lost and around correct inheritance of dependencies.require/dependencies.deny through extends: org.
Changes:
- Document
dependencies.require/dependencies.denyinheritance when repo policy usesextends: org. - Add a new “
required-packages-deployed” troubleshooting entry with symptoms/causes/remediation steps. - Add an install-failures troubleshooting section for policy blocks after a lockfile wipe/lockfile degradation.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/troubleshooting/policy-debugging.md | Adds troubleshooting notes for required-packages-deployed and documents fixed dependency inheritance semantics through extends: org. |
| docs/src/content/docs/troubleshooting/install-failures.md | Adds an install-failure section explaining the required-packages-deployed block after lockfile/deployed_files loss and suggested remediation. |
Copilot's findings
Comments suppressed due to low confidence (2)
docs/src/content/docs/troubleshooting/policy-debugging.md:192
- The "older versions" workaround appears incorrect: without the v0.14+ content-identical adopt behavior, a one-time
--no-policyrun will still treat the on-disk files as user-authored collisions (because they are not inmanaged_files) and will write an emptydeployed_filesback to the lockfile again. That means the next policy-enforced install will remain blocked. Consider updating this to recommend a one-time--force(with a warning about overwriting) or removing the affected deployed files before reinstalling, rather than implying--no-policyrepopulatesdeployed_fileson older versions.
- **Fix (older versions):** Use `--no-policy` once to break the loop, then run normally:
```bash
apm install --no-policy # one-time: repopulates deployed_files
apm install # policy now passes
**docs/src/content/docs/troubleshooting/install-failures.md:184**
* The "older than v0.14" guidance likely won't self-heal: on versions without byte-identical adopt, `--no-policy` does not repopulate `deployed_files` if the files already exist and are treated as user-authored collisions, so the next policy-enforced run will still be blocked. Please update this to a workaround that actually repopulates `deployed_files` on older versions (e.g. one-time `--force` with caution, or deleting the affected deployed files before reinstalling), or explicitly state that older versions may require continuing to use `--no-policy`/`--force` until upgrading.
On APM versions older than v0.14, use --no-policy once to break the loop:
apm install --no-policy # one-time: repopulates deployed_files
apm install # policy now passes</details>
- **Files reviewed:** 2/2 changed files
- **Comments generated:** 2
Comment on lines
+181
to
+187
| - **Fix (v0.14+):** Re-run `apm install`. APM now auto-adopts byte-identical existing files, which repopulates `deployed_files` without overwriting your content. The next `apm install` will then pass the policy gate. | ||
|
|
||
| ```bash | ||
| apm install # repopulates deployed_files; policy passes on this run | ||
| ``` | ||
|
|
||
| - **Fix (older versions):** Use `--no-policy` once to break the loop, then run normally: |
Comment on lines
+171
to
+177
| If `apm install` fails with `Policy violation: required-packages-deployed` right after a lockfile wipe, hand-edit, or partial-install crash, the lockfile has an empty `deployed_files` list for a required package even though the files are on disk. | ||
|
|
||
| Re-run `apm install` -- APM now auto-adopts byte-identical existing files and repopulates `deployed_files`, which lets the policy gate pass: | ||
|
|
||
| ```bash | ||
| apm install | ||
| ``` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation Updates - 2026-05-14
This PR updates the documentation based on features and fixes merged in the last 24 hours.
Features Documented
required-packages-deployedpolicy block after lockfile wipe (from fix: apm install no longer permanently blocked by policy after lockfile wipe (required-packages-deployed catch-22) #1313)dependencies.require/dependencies.denyinheritance throughextends: org(from fix(policy): layer dependencies.require through extends: org (closes #1201) #1290)Changes Made
docs/src/content/docs/troubleshooting/install-failures.mdto add a "Policy blocked after lockfile wipe" section describing therequired-packages-deployedcatch-22, the v0.14 self-healing behavior, and the older-version workarounddocs/src/content/docs/troubleshooting/policy-debugging.mdto addrequired-packages-deployedas a named common block scenario with fix instructions, and to note thatdependencies.require/denynow layer correctly throughextends: orgMerged PRs Referenced
Notes
apm pack) -- documentation was already included in that PR (pack.mdandpublish-to-a-marketplace.mdfully updated)baseline-checks.mdanddrift-detection.mdupdated)Note
🔒 Integrity filter blocked 9 items
The following items were blocked because they don't meet the GitHub integrity level.
search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".To allow these resources, lower
min-integrityin your GitHub frontmatter: